OpenEuphoria

note "format" is not unique, may need namespace prefix

----
----


@[:text:format|]
==== format
<eucode>
include text.e
namespace text
public function format(sequence format_pattern, object arg_list = {})
</eucode>

formats a set of arguments in to a string based on a supplied pattern.

===== Parameters:
# ##format_pattern## : A sequence: the pattern string that contains zero or more tokens.
# ##arg_list## : An object: Zero or more arguments used in token replacement.

===== Returns:
A string **sequence**, the original ##format_pattern## but with tokens replaced by
corresponding arguments.

===== Comments:
The ##format_pattern## string contains text and argument tokens. The resulting string
is the same as the format string except that each token is replaced by an
item from the argument list.

A token has the form **##[<Q>]##**, where ##<Q>## is are optional qualifier codes.

The qualifier. ##<Q>## is a set of zero or more codes that modify the default
way that the argument is used to replace the token. The default replacement
way is to convert the argument to its shortest string representation and
use that to replace the token. This may be modified by the following codes,
which can occur in any order.

|= Qualifier |= Usage |
| N | ('N' is an integer) The index of the argument to use|
| {id} | Uses the argument that begins with "id=" where "id" \\
is an identifier name. |
| %envvar% | Uses the Environment Symbol 'envar' as an argument |
| w | For string arguments, if capitalizes the first\\
letter in each word |
| u | For string arguments, it converts it to upper case. |
| l | For string arguments, it converts it to lower case. |
| < | For numeric arguments, it left justifies it. |
| > | For string arguments, it right justifies it. |
| c | Centers the argument. |
| z | For numbers, it zero fills the left side. |
| :S | ('S' is an integer) The maximum size of the\\
resulting field. Also, if 'S' begins with '0' the\\
field will be zero-filled if the argument is an integer|
| .N | ('N' is an integer) The number of digits after\\
the decimal point |
| + | For positive numbers, show a leading plus sign |
| ( | For negative numbers, enclose them in parentheses |
| b | For numbers, causes zero to be all blanks |
| s | If the resulting field would otherwise be zero\\
length, this ensures that at least one space occurs\\
between this token's field |
| t | After token replacement, the resulting string up to this point is trimmed. |
| X | Outputs integer arguments using hexadecimal digits. |
| B | Outputs integer arguments using binary digits. |
| ? | The corresponding argument is a set of two strings. This\\
uses the first string if the previous token's argument is\\
not the value 1 or a zero-length string, otherwise it\\
uses the second string. |
| [ | Does not use any argument. Outputs a left-square-bracket symbol |
| ,X | Insert thousands separators. The <X> is the character\\
to use. If this is a dot "." then the decimal point\\
is rendered using a comma. Does not apply to zero-filled\\
fields. \\
N.B. if hex or binary output was specified, the \\
separators are every 4 digits otherwise they are \\
every three digits. |
| T | If the argument is a number it is output as a text character, \\
otherwise it is output as text string |

Clearly, certain combinations of these qualifier codes do not make sense and in
those situations, the rightmost clashing code is used and the others are ignored.

Any tokens in the format that have no corresponding argument are simply removed
from the result. Any arguments that are not used in the result are ignored.

Any sequence argument that is not a string will be converted to its
//pretty// format before being used in token replacement.

If a token is going to be replaced by a zero-length argument, all white space
following the token until the next non-whitespace character is not copied to
the result string.

===== Example 1:
<eucode>
format("Cannot open file '[]' - code []", {"/usr/temp/work.dat", 32})
-- "Cannot open file '/usr/temp/work.dat' - code 32"

format("Err-[2], Cannot open file '[1]'", {"/usr/temp/work.dat", 32})
-- "Err-32, Cannot open file '/usr/temp/work.dat'"

format("[4w] [3z:2] [6] [5l] [2z:2], [1:4]", {2009,4,21,"DAY","MONTH","of"})
-- "Day 21 of month 04, 2009"

format("The answer is [:6.2]%", {35.22341})
-- "The answer is 35.22%"

format("The answer is [.6]", {1.2345})
-- "The answer is 1.234500"

format("The answer is [,,.2]", {1234.56})
-- "The answer is 1,234.56"

format("The answer is [,..2]", {1234.56})
-- "The answer is 1.234,56"

format("The answer is [,:.2]", {1234.56})
-- "The answer is 1:234.56"

format("[] [?]", {5, {"cats", "cat"}})
-- "5 cats"

format("[] [?]", {1, {"cats", "cat"}})
-- "1 cat"

format("[<:4]", {"abcdef"})
-- "abcd"

format("[>:4]", {"abcdef"})
-- "cdef"

format("[>:8]", {"abcdef"})
-- " abcdef"

format("seq is []", {{1.2, 5, "abcdef", {3}}})
-- `seq is {1.2,5,"abcdef",{3}}`

format("Today is [{day}], the [{date}]", {"date=10/Oct/2012", "day=Wednesday"})
-- "Today is Wednesday, the 10/Oct/2012"

format("'A' is [T]", 65)
-- `'A' is A`
</eucode>

===== See Also:
[[:sprintf]]